<!-- HTML header for doxygen 1.8.13-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>MTB CAT1 Peripheral driver library: I2S          (Inter-IC Sound)</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen_style.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><a href="http://www.cypress.com/"><img alt="Logo" src="IFXCYP_one-line.png"/></a></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">MTB CAT1 Peripheral driver library</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('group__group__i2s.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#groups">API Reference</a>  </div>
  <div class="headertitle">
<div class="title">I2S (Inter-IC Sound)</div>  </div>
</div><!--header-->
<div class="contents">
<a name="details" id="details"></a><h2 class="groupheader">General Description</h2>
<dl class="section note"><dt>Note</dt><dd>IP Supported: AUDIOSS </dd>
<dd>
Device Categories: CAT1A. Please refer <a href="usergroup1.html">Device Catalog</a>. The I2S driver provides a function API to manage Inter-IC Sound.</dd></dl>
<p>The functions and other declarations used in this driver are in cy_i2s.h. You can include cy_pdl.h to get access to all functions and declarations in the PDL.</p>
<p>I2S is used to send digital audio streaming data to external I2S devices, such as audio codecs or simple DACs. It can also receive digital audio streaming data.</p>
<p>Features:</p><ul>
<li>An industry standard NXP I2S interface.</li>
<li>Supports master/slave TX/RX operation.</li>
<li>Programmable Channel/Word Lengths.</li>
<li>Supports External Clock operation.</li>
</ul>
<p>The I2S bus is an industry standard. The hardware interface was developed by Philips Semiconductors (now NXP Semiconductors).</p>
<h1><a class="anchor" id="group_i2s_configuration_considerations"></a>
Configuration Considerations</h1>
<p>To set up an I2S, provide the configuration parameters in the <a class="el" href="structcy__stc__i2s__config__t.html">cy_stc_i2s_config_t</a> structure.</p>
<p>For example, for Tx configuration, set txEnabled to true, configure txDmaTrigger (depending on whether DMA is going to be used or not), set extClk (if an external clock is used), provide clkDiv, txMasterMode, txAlignment, txChannels (only are is supported in I2S and Left Justified modes) txSdoLatchingTime (for slave mode only), txChannelLength, txWordLength, txWsPulseWidth (for TMD modes only), txWatchdogEnable and txWatchdogValue (both for Slave mode only, and when the watchdog interrupt will be used), either txSckoInversion or txSckiInversion (based on txMasterMode setting), txFifoTriggerLevel (when the Trig interrupt will be used) and txOverheadValue (only when the word length is less than channel length). A similar setup is for the Rx configuration.</p>
<p>To initialize the I2S block, call the <a class="el" href="group__group__i2s__functions.html#ga7574dd2c887d3a97a9e4ffae4c586cf6">Cy_I2S_Init</a> function, providing the filled <a class="el" href="structcy__stc__i2s__config__t.html">cy_stc_i2s_config_t</a> structure. Before starting the transmission, clear the FIFO <a class="el" href="group__group__i2s__functions.html#ga8dda7998e6adb06e24d5b32433eaff7b">Cy_I2S_ClearTxFifo</a>, then fill the first Tx data frame by calling <a class="el" href="group__group__i2s__functions.html#ga7512a08a18a989cd46809ce75aa2dfa6">Cy_I2S_WriteTxData</a> once for each channel (e.g. twice for I2S mode with only two channels) with zero data. Then call the <a class="el" href="group__group__i2s__functions.html#ga7d690f4d128200b3c027fd07d8bcf972">Cy_I2S_EnableTx</a> itself. For the reception the sequence is the same except for filling the first data frame. Only clearing RX FIFO is enough.</p>
<p>For example: </p><div class="fragment"><div class="line">    <span class="comment">/* Scenario: Setup a duplex 16-bit I2S interface */</span></div><div class="line">    </div><div class="line">    <span class="keyword">const</span> <a class="code" href="structcy__stc__i2s__config__t.html">cy_stc_i2s_config_t</a> config =</div><div class="line">    {</div><div class="line">        <span class="comment">/* .txEnabled          */</span> <span class="keyword">true</span>,</div><div class="line">        <span class="comment">/* .rxEnabled          */</span> <span class="keyword">true</span>,</div><div class="line">        <span class="comment">/* .txDmaTrigger       */</span> <span class="keyword">false</span>,</div><div class="line">        <span class="comment">/* .rxDmaTrigger       */</span> <span class="keyword">false</span>,</div><div class="line">        <span class="comment">/* .clkDiv             */</span> 16U,</div><div class="line">        <span class="comment">/* .extClk             */</span> <span class="keyword">false</span>,</div><div class="line">        <span class="comment">/* .txMasterMode       */</span> <span class="keyword">false</span>,</div><div class="line">        <span class="comment">/* .txAlignment        */</span> <a class="code" href="group__group__i2s__enums.html#ggac2ba15c8dab8fc0c422ab369992636f5ae42d0ade64f2daf741c905db1034188b">CY_I2S_I2S_MODE</a>,</div><div class="line">        <span class="comment">/* .txWsPulseWidth     */</span> <a class="code" href="group__group__i2s__enums.html#gga265f4e0f0d40f96b383a91aab3215f79a4ac9c0b6c81f4ceb4fa17f83ff96e912">CY_I2S_WS_ONE_CHANNEL_LENGTH</a>,</div><div class="line">        <span class="comment">/* .txWatchdogEnable   */</span> <span class="keyword">false</span>,</div><div class="line">        <span class="comment">/* .txWatchdogValue    */</span> 0xFFFFFFFFUL,</div><div class="line">        <span class="comment">/* .txSdoLatchingTime  */</span> <span class="keyword">false</span>,</div><div class="line">        <span class="comment">/* .txSckoInversion    */</span> <span class="keyword">false</span>,</div><div class="line">        <span class="comment">/* .txSckiInversion    */</span> <span class="keyword">false</span>,</div><div class="line">        <span class="comment">/* .txChannels         */</span> 2U,</div><div class="line">        <span class="comment">/* .txChannelLength    */</span> <a class="code" href="group__group__i2s__enums.html#gga23a77f23cf018c0a0ca3874a0709a630a4b0d03407d5b1d135784e77570613ae5">CY_I2S_LEN16</a>,</div><div class="line">        <span class="comment">/* .txWordLength       */</span> <a class="code" href="group__group__i2s__enums.html#gga23a77f23cf018c0a0ca3874a0709a630a4b0d03407d5b1d135784e77570613ae5">CY_I2S_LEN16</a>,</div><div class="line">        <span class="comment">/* .txOverheadValue    */</span> <a class="code" href="group__group__i2s__enums.html#ggace34f02636657f8a8f1290fcbc5acfa6ab0df85606cde8ff2d5b0c58dd3f7193c">CY_I2S_OVHDATA_ZERO</a>,</div><div class="line">        <span class="comment">/* .txFifoTriggerLevel */</span> 0U, <span class="comment">/* In this example the trigger isn&#39;t used */</span></div><div class="line">        <span class="comment">/* .rxMasterMode       */</span> <span class="keyword">true</span>,</div><div class="line">        <span class="comment">/* .rxAlignment        */</span> <a class="code" href="group__group__i2s__enums.html#ggac2ba15c8dab8fc0c422ab369992636f5ae42d0ade64f2daf741c905db1034188b">CY_I2S_I2S_MODE</a>,</div><div class="line">        <span class="comment">/* .rxWsPulseWidth     */</span> <a class="code" href="group__group__i2s__enums.html#gga265f4e0f0d40f96b383a91aab3215f79a4ac9c0b6c81f4ceb4fa17f83ff96e912">CY_I2S_WS_ONE_CHANNEL_LENGTH</a>,</div><div class="line">        <span class="comment">/* .rxWatchdogEnable   */</span> <span class="keyword">false</span>,</div><div class="line">        <span class="comment">/* .rxWatchdogValue    */</span> 0xFFFFFFFFUL,</div><div class="line">        <span class="comment">/* .rxSdiLatchingTime  */</span> <span class="keyword">false</span>,</div><div class="line">        <span class="comment">/* .rxSckoInversion    */</span> <span class="keyword">false</span>,</div><div class="line">        <span class="comment">/* .rxSckiInversion    */</span> <span class="keyword">false</span>,</div><div class="line">        <span class="comment">/* .rxChannels         */</span> 2U,</div><div class="line">        <span class="comment">/* .rxChannelLength    */</span> <a class="code" href="group__group__i2s__enums.html#gga23a77f23cf018c0a0ca3874a0709a630a4b0d03407d5b1d135784e77570613ae5">CY_I2S_LEN16</a>,</div><div class="line">        <span class="comment">/* .rxWordLength       */</span> <a class="code" href="group__group__i2s__enums.html#gga23a77f23cf018c0a0ca3874a0709a630a4b0d03407d5b1d135784e77570613ae5">CY_I2S_LEN16</a>,</div><div class="line">        <span class="comment">/* .rxSignExtension    */</span> <span class="keyword">false</span>,</div><div class="line">        <span class="comment">/* .rxFifoTriggerLevel */</span> 0U <span class="comment">/* In this example the trigger isn&#39;t used */</span></div><div class="line">    };</div><div class="line">    </div><div class="line">    <span class="keywordflow">if</span>(<a class="code" href="group__group__i2s__enums.html#gga49f7fb887e336a0b459c022cd99f4fa3a2f64d83f74b115135886e89ca315a98b">CY_I2S_SUCCESS</a> != <a class="code" href="group__group__i2s__functions.html#ga7574dd2c887d3a97a9e4ffae4c586cf6">Cy_I2S_Init</a> (I2S0, &amp;config))</div><div class="line">    {</div><div class="line">        <span class="comment">/* Insert error handling */</span></div><div class="line">    }</div><div class="line">    </div><div class="line">    <span class="comment">/* Clear both FIFOs */</span></div><div class="line">    <a class="code" href="group__group__i2s__functions.html#ga11c903a4a6fb573bf85e83082f898352">Cy_I2S_ClearRxFifo</a> (I2S0);</div><div class="line">    <a class="code" href="group__group__i2s__functions.html#ga8dda7998e6adb06e24d5b32433eaff7b">Cy_I2S_ClearTxFifo</a> (I2S0);</div><div class="line">    <span class="comment">/* Put at least one frame (may be empty) into the Tx FIFO - two data words for I2S format */</span></div><div class="line">    <a class="code" href="group__group__i2s__functions.html#ga7512a08a18a989cd46809ce75aa2dfa6">Cy_I2S_WriteTxData</a> (I2S0, 0UL);</div><div class="line">    <a class="code" href="group__group__i2s__functions.html#ga7512a08a18a989cd46809ce75aa2dfa6">Cy_I2S_WriteTxData</a> (I2S0, 0UL);</div><div class="line">    <span class="comment">/* Clear possible pending interrupts */</span></div><div class="line">    <a class="code" href="group__group__i2s__functions.html#ga7f7dde04f9940070daef8999eab4b5ac">Cy_I2S_ClearInterrupt</a> (I2S0, <a class="code" href="group__group__i2s__macros__interrupt__masks.html#gadc2be4eeee3e8b5a0d54bd6e881f5218">CY_I2S_INTR_TX_EMPTY</a>);</div><div class="line">    <span class="comment">/* Enable interrupts */</span></div><div class="line">    <a class="code" href="group__group__i2s__functions.html#ga3add2008780c377c10dd3231d97182de">Cy_I2S_SetInterruptMask</a> (I2S0, <a class="code" href="group__group__i2s__macros__interrupt__masks.html#gadc2be4eeee3e8b5a0d54bd6e881f5218">CY_I2S_INTR_TX_EMPTY</a> | <a class="code" href="group__group__i2s__macros__interrupt__masks.html#gaa3ab58981323c1646276eb0e53fc0e3f">CY_I2S_INTR_RX_FULL</a>);</div><div class="line">    <span class="comment">/* Enable communication */</span></div><div class="line">    <a class="code" href="group__group__i2s__functions.html#gaedf461d1a75f8b244701a4703d1fe539">Cy_I2S_EnableRx</a> (I2S0);</div><div class="line">    <a class="code" href="group__group__i2s__functions.html#ga7d690f4d128200b3c027fd07d8bcf972">Cy_I2S_EnableTx</a> (I2S0);</div></div><!-- fragment --><p> If you use a DMA, the DMA channel should be previously configured. The I2S interrupts (if applicable) can be enabled by calling <a class="el" href="group__group__i2s__functions.html#ga3add2008780c377c10dd3231d97182de">Cy_I2S_SetInterruptMask</a>.</p>
<p>For example, if the trigger interrupt is used during operation, the ISR should call the <a class="el" href="group__group__i2s__functions.html#ga7512a08a18a989cd46809ce75aa2dfa6">Cy_I2S_WriteTxData</a> as many times as required for your FIFO payload, but not more than the FIFO size. Then call <a class="el" href="group__group__i2s__functions.html#ga7f7dde04f9940070daef8999eab4b5ac">Cy_I2S_ClearInterrupt</a> with appropriate parameters.</p>
<p>The I2S/Left Justified data formats always contains two data channels. They are ordered one-by-one in the FIFOs and left always goes first. So in case of mono audio stream transmission, each sample can be put twice into the TX FIFO (in this case both channels will sound the same), or combined with zeroes: sample1-zero-sample2-zero (in this case only the left channel will finally sound, for a right-only case, zero should go first). The TDM frame word order in FIFOs is similar, one-by-one.</p>
<p>If a DMA is used and the DMA channel is properly configured - no CPU activity (or any application code) is needed for I2S operation.</p>
<p>The I2S frame appears as: </p><div class="image">
<img src="i2s_frame.png" alt="i2s_frame.png"/>
</div>
<p> This is an example for the channel length = 32. A similar case exists for the rest channel lengths, with one limitation: the word length could be less than or equal to the channel length. See the device technical reference manual (TRM) for more details.</p>
<h1><a class="anchor" id="group_i2s_more_information"></a>
More Information</h1>
<p>See: the the I2S chapter of the device technical reference manual (TRM); I2S_PDL Component datasheet; CE218636 - PSOC 6 MCU INTER-IC SOUND (I2S) EXAMPLE.</p>
<h1><a class="anchor" id="group_i2s_changelog"></a>
Changelog</h1>
<table class="doxtable">
<tr>
<th>Version</th><th>Changes</th><th>Reason for Change </th></tr>
<tr>
<td>2.30 </td><td>Update to configure MCLK. </td><td>Update to configure i2S on core CM7.  </td></tr>
<tr>
<td>2.20 </td><td>Fixed/documented MISRA 2012 violations. </td><td>MISRA 2012 compliance.  </td></tr>
<tr>
<td>2.10.1 </td><td>Minor documentation updates. </td><td>Documentation enhancement.  </td></tr>
<tr>
<td rowspan="2">2.10 </td><td>Flattened the organization of the driver source code into the single source directory and the single include directory.  </td><td>Driver library directory-structure simplification.  </td></tr>
<tr>
<td>Added register access layer. Use register access macros instead of direct register access using dereferenced pointers. </td><td>Makes register access device-independent, so that the PDL does not need to be recompiled for each supported part number.  </td></tr>
<tr>
<td>2.0.1 </td><td>Added Low Power Callback section </td><td>Documentation update and clarification  </td></tr>
<tr>
<td>2.0 </td><td>The slave operation is added, Left Justified and TDM modes are added </td><td></td></tr>
<tr>
<td>1.0 </td><td>Initial version </td><td></td></tr>
</table>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="groups"></a>
API Reference</h2></td></tr>
<tr class="memitem:group__group__i2s__macros"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__i2s__macros.html">Macros</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__i2s__functions"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__i2s__functions.html">Functions</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__i2s__data__structures"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__i2s__data__structures.html">Data Structures</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__i2s__enums"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__i2s__enums.html">Enumerated Types</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part
<div id="nav-path" class="navpath">
    <ul>
        <li class="footer">
            Generated for <b>MTB CAT1 Peripheral driver library</b> by <b>Cypress Semiconductor Corporation</b>.
            All rights reserved.
        </li>
    </ul>
</div>
-->
</body>
</html>
